﻿using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using lucere.entity;

namespace lucere.analysis
{
    /// <summary>An Analyzer builds TokenStreams, which analyze text.  It thus represents a
    /// policy for extracting index terms from text.
    /// <p/>
    /// Typical implementations first build a Tokenizer, which breaks the stream of
    /// characters from the Reader into raw Tokens.  One or more TokenFilters may
    /// then be applied to the output of the Tokenizer.
    /// </summary>
    public interface IAnalyzer : IDisposable
    {
        /// <summary> Just like {@link #getPositionIncrementGap}, except for
        /// Token offsets instead.  By default this returns 1 for
        /// tokenized fields and, as if the fields were joined
        /// with an extra space character, and 0 for un-tokenized
        /// fields.  This method is only called if the field
        /// produced at least one token for indexing.
        /// 
        /// </summary>
        /// <param name="field">the field just indexed
        /// </param>
        /// <returns> offset gap, added to the next token emitted from {@link #TokenStream(String,Reader)}
        /// </returns>
        int GetOffsetGap(IFieldable field);

        /// <summary> Invoked before indexing a Fieldable instance if
        /// terms have already been added to that field.  This allows custom
        /// analyzers to place an automatic position increment gap between
        /// Fieldable instances using the same field name.  The default value
        /// position increment gap is 0.  With a 0 position increment gap and
        /// the typical default token position increment of 1, all terms in a field,
        /// including across Fieldable instances, are in successive positions, allowing
        /// exact PhraseQuery matches, for instance, across Fieldable instance boundaries.
        /// 
        /// </summary>
        /// <param name="fieldName">Fieldable name being indexed.
        /// </param>
        /// <returns> position increment gap, added to the next token emitted from {@link #TokenStream(String,Reader)}
        /// </returns>
        int GetPositionIncrementGap(string fieldName);

        /// <summary>Creates a TokenStream that is allowed to be re-used
        /// from the previous time that the same thread called
        /// this method.  Callers that do not need to use more
        /// than one TokenStream at the same time from this
        /// analyzer should use this method for better
        /// performance.
        /// </summary>
        ITokenStream ReusableTokenStream(string fieldName, TextReader reader);

        /// <summary>Used by Analyzers that implement reusableTokenStream
        /// to retrieve previously saved TokenStreams for re-use
        /// by the same thread. 
        /// </summary>
        object PreviousTokenStream { get; set; }

        /// <summary>Creates a TokenStream which tokenizes all the text in the provided
        /// Reader.  Must be able to handle null field name for
        /// backward compatibility.
        /// </summary>
        ITokenStream TokenStream(string paramString, TextReader paramReader);
    }
}
